/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License"),
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup TeeTrusted
 * @{
 *
 * @brief TEE（Trusted Excution Environment）可信执行环境API。
 *
 * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。
 *
 * @since 20
 */

/**
 * @file tee_property_api.h
 *
 * @brief TEE对象API定义的参考。
 *
 * @library NA
 * @kit TEEKit
 * @include <TEEKit/tee_property_api.h>
 * @syscap SystemCapability.Tee.TeeClient
 * @since 20
 */

#ifndef TEE_PROPERTY_API_H
#define TEE_PROPERTY_API_H

#include "tee_defines.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 枚举属性集的类型。
 *
 * @since 20
 */
typedef enum {
    /** 未知的属性集类型。 */
    TEE_PROPSET_UNKNOW             = 0,
    /** TEE实现的属性集类型。 */
    TEE_PROPSET_TEE_IMPLEMENTATION = 0xFFFFFFFD,
    /** 当前客户端的属性集类型。 */
    TEE_PROPSET_CURRENT_CLIENT     = 0xFFFFFFFE,
    /** 当前可信应用 (TA) 的属性集类型。 */
    TEE_PROPSET_CURRENT_TA         = 0xFFFFFFFF,
} Pseudo_PropSetHandle;

/**
 * @brief 定义属性集句柄类型。
 *
 * @since 20
 */
typedef uint32_t TEE_PropSetHandle;

/**
 * @brief 从属性集中获取属性并将其值转换为可打印字符串。
 *
 * @param propsetOrEnumerator 指向一个TEE_PROPSET_XXX伪句柄或属性枚举器句柄。
 * @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。
 * @param valueBuffer 指向用于存储获取到的属性值的缓冲区的指针。
 * @param valueBufferLen 指向缓冲区长度的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
 *         TEE_ERROR_SHORT_BUFFER：值缓冲区的空间不足以存储获取的属性值。
 * @since 20
 */
TEE_Result TEE_GetPropertyAsString(TEE_PropSetHandle propsetOrEnumerator, const char *name, char *valueBuffer,
    size_t *valueBufferLen);

/**
* @brief 从属性集中获取属性并将其值转换为布尔值。
*
* @param propsetOrEnumerator 指向一个TEE_PROPSET_XXX伪句柄或属性枚举器句柄。
* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。
* @param value 指向用于存储获取到的属性值的变量的指针。
*
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
* @since 20
*/
TEE_Result TEE_GetPropertyAsBool(TEE_PropSetHandle propsetOrEnumerator, const char *name, bool *value);

/**
* @brief 从属性集中获取属性并将其值转换为32位无符号整数。
*
* @param propsetOrEnumerator 指向一个TEE_PROPSET_XXX伪句柄或属性枚举器句柄。
* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。
* @param value 指向用于存储获取到的属性值的变量的指针。
*
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
* @since 20
*/
TEE_Result TEE_GetPropertyAsU32(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint32_t *value);

#if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2)
/**
 * @brief 从属性集中获取属性并将其值转换为64位无符号整数。
 *
 * @param propsetOrEnumerator 指向一个TEE_PROPSET_XXX伪句柄或属性枚举器句柄。
 * @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。
 * @param value 指向用于存储获取到的属性值的变量的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
 * @since 20
 */
TEE_Result TEE_GetPropertyAsU64(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint64_t *value);
#endif // API_LEVEL

/**
 * @brief 从属性集中获取属性并将其值转换为二进制块。
 *
 * @param propsetOrEnumerator 指向一个TEE_PROPSET_XXX伪句柄或属性枚举器句柄。
 * @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。
 * @param valueBuffer 指向用于存储获取到的属性值的缓冲区的指针。
 * @param valueBufferLen 指向缓冲区长度的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
 *         TEE_ERROR_SHORT_BUFFER：值缓冲区的空间不足以存储获取的属性值。
 * @since 20
 */
TEE_Result TEE_GetPropertyAsBinaryBlock(TEE_PropSetHandle propsetOrEnumerator, const char *name, void *valueBuffer,
    size_t *valueBufferLen);

/**
* @brief 从属性集中获取属性并将其值转换为TEE_UUID结构体。
*
* @param propsetOrEnumerator 指向一个TEE_PROPSET_XXX伪句柄或属性枚举器句柄。
* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。
* @param value 指向用于存储获取到的属性值的变量的指针。
*
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
* @since 20
*/
TEE_Result TEE_GetPropertyAsUUID(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_UUID *value);

/**
* @brief 从属性集中获取属性并将其值转换为TEE_Identity结构体。
*
* @param propsetOrEnumerator 指向一个TEE_PROPSET_XXX伪句柄或属性枚举器句柄。
* @param name 指向包含要获取的属性名称的以零结尾的字符串的指针。
* @param value 指向用于存储获取到的属性值的变量的指针。
*
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
* @since 20
*/
TEE_Result TEE_GetPropertyAsIdentity(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_Identity *value);

/**
 * @brief 分配一个属性枚举器对象。
 *
 * @param enumerator 指向用于存储分配的属性枚举器句柄的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_OUT_OF_MEMORY：资源不足，无法分配属性枚举器。
 * @since 20
 */
TEE_Result TEE_AllocatePropertyEnumerator(TEE_PropSetHandle *enumerator);

/**
 * @brief 释放一个属性枚举器对象。
 *
 * @param enumerator 指向要释放的属性枚举器的句柄。
 *
 * @return 无返回值。
 *
 * @since 20
 */
void TEE_FreePropertyEnumerator(TEE_PropSetHandle enumerator);

/**
 * @brief 开始枚举属性枚举器中的属性。
 *
 * @param enumerator 指向属性枚举器的句柄。
 * @param propSet 指向要枚举的属性集的伪句柄。
 *
 * @return 无返回值。
 *
 * @since 20
 */
void TEE_StartPropertyEnumerator(TEE_PropSetHandle enumerator, TEE_PropSetHandle propSet);

/**
 * @brief 立即重置属性枚举器（通常在分配后执行）。
 *
 * @param enumerator 指向要重置的属性枚举器的句柄。
 *
 * @return 无返回值。
 *
 * @since 20
 */
void TEE_ResetPropertyEnumerator(TEE_PropSetHandle enumerator);

/**
 * @brief 获取枚举器中当前属性的名称。
 *
 * @param enumerator 指向属性枚举器的句柄。
 * @param nameBuffer 指向用于存储获取到的属性名称的缓冲区的指针。
 * @param nameBufferLen 指向缓冲区长度的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
 *         TEE_ERROR_SHORT_BUFFER：值缓冲区的空间不足以存储获取的属性值。
 * @since 20
 */
TEE_Result TEE_GetPropertyName(TEE_PropSetHandle enumerator, void *nameBuffer, size_t *nameBufferLen);

/**
 * @brief 获取枚举器中的下一个属性。
 *
 * @param enumerator 指向属性枚举器的句柄。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法获取目标属性。\n
 * @since 20
 */
TEE_Result TEE_GetNextProperty(TEE_PropSetHandle enumerator);

#ifdef __cplusplus
}
#endif

#endif
/** @} */